Proposal

Introduce a new parameter streamAgentTools in StreamRunOptions. When set to true, the StreamRunResult object returned by Runner.run() contains all stream events from current agent, and all agents invoked via agent-as-tools, recursively.

For example, the following setup:

const agentB = new Agent(...);
const agentA = new Agent(
  ..., 
  tools=[agentB.asTool(...)]
);
const runner = new Runner(...);
const result = runner.run(
  agentA,
  'Solve task by using agentB as a tool',
  {
    stream: true,
    streamAgentTools: true,
  }
);

We can consume events by for await (const event of result) {...}, and events originate from both agent A and agent B.

Background

I was working on an app with a main agent using other tool agents as tools, for better responsibility separation. To provide live update to end users, I process stream events from the main agent. In current implementation, the events from main stream only consist of tool_called / tool_output in run item events, or corresponding raw events.

This behavior creates a challenge for live updates - end users can see that the main agent is invoking a tool, but it may look stuck if tool agent takes a while to run. Although there are workarounds like writing updates in agent hooks, they all require code changes to handle this case. What I needed was a straightforward toggle to enable stream events from all agents recursively, working with agent-as-tools, handoffs, etc.

I see similar PRs requesting for features in the Python library, so I feel that this is a pretty common use case.

Implementation details

I added a context-scope stream that all runners invoked with a single RunContext can use to send stream events. The first runner owns the stream, and other runner (initialized indirectly inside asTool()) copies events to the context-scope stream if necessary.

Changes

1. added streamAgentTools in StreamRunOptions
2. updated StreamRunResult to handle streamAgentTools; created context-scope stream; copied events to the context-scope stream; handled completion/abort/failure scenarios
3. updated asTool execute method to check run context; if enabled, passed StreamRunOptions to runner and await for completion
4. added a stream-agent-tools.ts example snippet
5. unit tests

Unrelated fix

This PR also contains 2 commits to (1) remove redundant tool name replacement (non-alphanumeric -> underscore already handles space -> underscore), and (2) fix a typo (Schame -> Schema).